Documentation Section
Sections are objects that create logical sections for documentation generation withing a group.
id
– {string}
–
The unique id that is used internally and appears within the url for each doc parsed
title
– {string}
–
The title of the section that is used often in the UI
showSource
– {boolean}
–
Defaults to false. When true will copy all source files to the webapp so they can be displayed in the UI. WARNING All files within this section should be considered public. All information should be considered insecure. Note, this section level 'showSource' configuration will override the group level setting.
scripts
– {array : paths}
–
An array of paths that may reference a directory or a single file. The single file or every file in the directory will be scanned for documentation THAT IS WITHIN BLOCK COMMENTS.
/** * @doc docType * @doc id * @doc name * @doc description */
docs
– {array : paths}
–
An array of paths that may reference a directory or a single file. The single file or every file in the directory will be scanned for documentation THAT IS NOT WITHIN COMMENTS.
@doc docType @doc id @doc name @doc description
rank
– {object}
–
The rank object contains key value pairs, where the key is an id of a document and the value is the ranking associated with that document. This object is used to place sections in order within the UI. If a document does not have a rank, it is automatically set to a large number (which pushes it to the bottom).
Below we have included ONE of the sections normally added for the default Docular documenation
module.exports = function(grunt) { // Project configuration grunt.initConfig({ pkg: grunt.file.readJSON('package.json'), docular: { groups: [ { groupTitle: 'Docular', groupId: 'docular', groupIcon: 'icon-beer', sections: [ { id: "docularinstall", title: "Install Docular", showSource: false, docs: [ "lib/scripts/docs/install" ], rank: { 'installnode':1, 'installgrunt':2, 'installdocular':3 } }, //the rest of the section objects ommitted ] } ], //other configurations ommitted here for simplicity } }); // Load the plugin that provides the "docular" tasks. grunt.loadNpmTasks('grunt-docular'); // Default task(s). grunt.registerTask('default', ['docular']); };
We provide two buckets, "docs", and "scripts" as configurations within a section object. You can certainly use both within one section but understanding the difference is important.
Every directory or filename specified within the "docs" array will be parsed for documentation that exists NOT within comments in that file. So "docs" files are meant to basically be non-code files with "overview" or "tutorial" type information. Doc files are there for providing a more convient way of creating documentation that doesn't necessarily depend on actual code.
As of this writing, all "doc" files should have a ".doc" or ".ngdoc" extension.
If you specify a file or directory within the "scripts" array, those files will all be scanned for documentation WITHIN block comments. This is a great way to add documentation inline and near your actual code.
There is a lot of flexibility so just follow what works for your project.
{ groupTitle: 'Docular', groupId: 'docular', groupIcon: 'icon-edit', descr: 'Description', showSource: true, sections: [ { id: "docularinstall", title: "Install Docular", docs: [ "lib/scripts/docs/install" ], rank: { 'installnode':1, 'installgrunt':2, 'installdocular':3 } }, { id: "docularconfigure", title: "Docular Configurations", docs: [ "lib/scripts/docs/configure" ], rank: { 'show':1, 'groups':2, 'sections':3, 'discussions':4, 'analytics':5, 'partials':6, 'ui':7 } }, { id: "docularcreate", title: "Documentation Groups and Sections", docs: [ "lib/scripts/docs/create" ], rank: {'configuregroup':1, 'configuresection':2, 'firstdoc':3} }, { id: "embed", title: "Embedding Documentation", docs: [ "lib/scripts/docs/embed" ], rank: {'blockdef_js':1, 'blockdef_doc':2} }, { id: 'basics', title: 'Documentation Basics', docs: [ "lib/scripts/docs/basics" ], rank : { 'identifier':1, 'naming':2, 'fields':3, 'modules':4, 'sections':5, 'types':6, 'types_doc':7, 'types_ngdoc':8, 'children':9, 'links':10 } }, { id: "doctypes", title: 'Documentation Types (DocTypes)', docs: [ "lib/scripts/docs/doctypes/doctypes.doc" ], rank : {'types_doc':2, 'types_ngdoc':3} }, { id: "docularext", title:"Docular Extensions", scripts: [], docs: [ "lib/scripts/docs/extensions" ] }, { id: "docular", title:"Docular Source", scripts: [ "lib/scripts/gen-docs.js", "lib/scripts/reader.js", "lib/scripts/writer.js", "lib/scripts/Doc.js" ], docs : [ "lib/scripts/docs/node", "README.md" ] }, { id: "docularfaq", title:"FAQs", scripts: [], docs: [ "lib/scripts/docs/faq" ] } ] }
We made some small tweaks, but ported over most of the AngularJS "scripts" and "docs" in tact.
{ groupTitle: 'Angular', groupId: 'angular', groupIcon: 'icon-book', sections: [ { id: "api", title:"Angular API", scripts: ["lib/angular/js"] }, { id: "guide", title: "Developers Guide", docs: ["lib/angular/ngdocs/guide"] }, { id: "tutorial", title: "Tutorial", docs: ["lib/angular/ngdocs/tutorial"] }, { id: "misc", title: "Overview", docs: ["lib/angular/ngdocs/misc"] } ] }